/**
 * <h3>IOpusService</h3>
 * <p> 作品服务接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义作品相关的业务操作接口，包括作品的增删改查、设计师管理、校园大使比赛等功能 </p>
 * <p> 支持作品列表查询、用户作品管理、比赛排名计算等核心业务逻辑 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *    <li> 作者：郭强 </li>
 *    <li> 创建日期：2025年05月06日 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *    <li> 示例代码：{@code selectOpusList(OpusDTO dto)} </li>
 * </ul>
 *
 * @apiNote 继承自MyBatis-Plus的IService接口，提供基础CRUD操作
 * @implSpec 继承自 {@link IService<OpusDTO>}
 * @since v1.0.0
 */

package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.Opus;
import com.dnndo.system.domain.OpuslistsToUserInfo;
import com.dnndo.system.domain.dto.*;
import com.dnndo.system.domain.vo.AmbassadorVO;
import com.dnndo.system.domain.vo.ApiOpusEnVO;
import com.dnndo.system.domain.vo.ApiOpusZhVO;
import com.dnndo.system.domain.vo.DesignerVO;

import java.util.List;

/**
 * 作品服务接口
 * 
 * @see com.dnndo.system.domain.Opus
 * @see com.dnndo.system.domain.dto.OpusDTO
 * @see com.dnndo.system.service.impl.OpusServiceImpl
 */
public interface IOpusService extends IService<OpusDTO> {

    /**
     * 根据条件分页查询作品列表
     *
     * @param dto 作品查询条件封装对象，包含名称、用户ID等过滤条件
     * @return List<Opus> 符合条件的作品信息列表
     * @see com.dnndo.system.domain.dto.OpusDTO
     * @see com.dnndo.system.domain.Opus
     */
    List<Opus> selectOpusList(OpusDTO dto);

    /**
     * 查询设计师列表
     *
     * @param dto 作品查询条件封装对象，包含名称、用户ID等过滤条件
     * @return List<OpusDTO> 符合条件的作品信息列表
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    List<OpusDTO> selectdesignerlist(OpusDTO dto);

    /**
     * 根据作品ID获取详细信息
     *
     * @param opusId 作品唯一标识符
     * @param uID 用户ID，用于权限验证
     * @return OpusDTO 包含作品详细信息的数据对象
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    OpusDTO selectOpusListById(Long opusId, Long uID);
    
    /**
     * 根据用户ID获取详细信息
     *
     * @param userId 用户唯一标识符
     * @return OpusDTO 包含用户作品详细信息的数据对象
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    OpusDTO selectdesignerListById(Long userId);

    /**
     * 修改已有作品信息
     *
     * @param opusDTO 包含更新字段的作品数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    int updateOpusById(OpusDTO opusDTO);

    /**
     * 新增作品信息
     *
     * @param opusDTO 包含新增字段的作品数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    int insertOpus(OpusDTO opusDTO);

    /**
     * 删除指定ID的作品信息
     *
     * @param opusId 要删除的作品唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    int deleteOpusById(Integer opusId);
    
    /**
     * 删除指定ID的作品信息（重载方法）
     *
     * @param opusId 要删除的作品唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    int delOpusById(Integer opusId);

    /**
     * 查询校园品牌馆信息
     *
     * @param dto 查询条件封装对象
     * @return List<BrandPavilionDTO> 查询结果集
     * @see com.dnndo.system.domain.dto.BrandPavilionDTO
     */
    List<BrandPavilionDTO> selectCampusBrandPavilion(BrandPavilionDTO dto);

    /**
     * 获取校园大使信息
     *
     * @param dto 校园大使查询条件
     * @return List<AmbassadorVO> 校园大使信息列表
     * @see com.dnndo.system.domain.dto.AmbassadorDTO
     * @see com.dnndo.system.domain.vo.AmbassadorVO
     */
    List<AmbassadorVO> getAmbassadorInfo(AmbassadorDTO dto);

    /**
     * 获取校园设计师信息
     *
     * @param params 设计师查询参数
     * @return List<DesignerVO> 设计师信息列表
     * @see com.dnndo.system.domain.dto.DesignerDTO
     * @see com.dnndo.system.domain.vo.DesignerVO
     */
    List<DesignerVO> designer(DesignerDTO params);

    /**
     * 文创活动-根据作品id，查询相关作品及用户信息
     *
     * @param params 文创活动查询参数
     * @return CulturalDTO 文创活动相关信息
     * @see com.dnndo.system.domain.dto.CulturalDTO
     */
    CulturalDTO cultural(CulturalDTO params);

    /**
     * 根据用户id，查询该用户的所有相关作品
     *
     * @param params 用户作品查询参数
     * @return List<OpuslistWithUserInfoDTO> 用户作品列表
     * @see com.dnndo.system.domain.dto.OpuslistWithUserInfoDTO
     */
    List<OpuslistWithUserInfoDTO> getWorkListWithUserInfo(OpuslistWithUserInfoDTO params);

    /**
     * 首页-文创活动（中文版）
     *
     * @return ApiOpusZhVO 中文版文创活动信息
     * @see com.dnndo.system.domain.vo.ApiOpusZhVO
     */
    ApiOpusZhVO selectApiOpusActivitiesZh();
    
    /**
     * 首页-文创活动（英文版）
     *
     * @return ApiOpusEnVO 英文版文创活动信息
     * @see com.dnndo.system.domain.vo.ApiOpusEnVO
     */
    ApiOpusEnVO selectApiOpusActivitiesEn();

    /**
     * 检查用户是否已参加指定主题
     *
     * @param themeId 主题ID
     * @param userId 用户ID
     * @return boolean 是否已参加
     * @see com.dnndo.system.domain.Theme
     */
    boolean checkUserJoined(Long themeId, Long userId);

    /**
     * 根据作品ID查询作品信息
     *
     * @param opusId 作品ID
     * @return OpusDTO 作品信息
     * @see com.dnndo.system.domain.dto.OpusDTO
     */
    OpusDTO selectOpusById(Long opusId);

    /**
     * 校园大使比赛策略-计算并排名作品
     *
     * @param themeId 主题ID
     * @see com.dnndo.system.domain.Theme
     */
    void calculateAndRankOpusByThemeId(Integer themeId);

    /**
     * 查询校园品牌馆信息的总记录数
     *
     * @param dto 查询条件
     * @return int 总记录数
     * @see com.dnndo.system.domain.dto.BrandPavilionDTO
     */
    int countCampusBrandPavilion(BrandPavilionDTO dto);

    /**
     * 查询校园大使的总记录数
     *
     * @param dto 查询条件
     * @return int 总记录数
     * @see com.dnndo.system.domain.dto.AmbassadorDTO
     */
    int countAmbassador(AmbassadorDTO dto);

    /**
     * 查询设计师的总记录数
     *
     * @param dto 查询条件
     * @return int 总记录数
     * @see com.dnndo.system.domain.dto.DesignerDTO
     */
    int countDesigner(DesignerDTO dto);

    /**
     * 查询根据用户id，查询该用户的所有相关作品总数
     *
     * @param dto 查询条件
     * @return int 总记录数
     * @see com.dnndo.system.domain.dto.OpuslistWithUserInfoDTO
     */
    int countWorkListWithUserInfo(OpuslistWithUserInfoDTO dto);

    /**
     * 根据用户ID获取作品列表信息
     *
     * @param opuslistsToUserInfo 查询条件
     * @return List<OpuslistsToUserInfo> 作品列表
     * @see com.dnndo.system.domain.OpuslistsToUserInfo
     */
    List<OpuslistsToUserInfo> getOpusListsByUserId(OpuslistsToUserInfo opuslistsToUserInfo);
}
